home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / PSTReadImageHeader.z / PSTReadImageHeader
Encoding:
Text File  |  2002-10-03  |  11.9 KB  |  265 lines
  1.  
  2.  
  3.  
  4. PPPPSSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((3333))))            IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo             PPPPSSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      PSTReadImageHeader, PSTWriteImageHeader - read/write printing specific
  10.      STIFF image header
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttddddiiiioooo....hhhh>>>>
  14.      ####iiiinnnncccclllluuuuddddeeee <<<<pppprrrriiiinnnnttttssssttttiiiiffffffff....hhhh>>>>
  15.  
  16.      iiiinnnntttt PPPPSSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((SSSSTTTTSSSSttttrrrreeeeaaaammmm ****sssstttt,,,, PPPPSSSSTTTTIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr ****hhhhdddd))));;;;
  17.  
  18.      iiiinnnntttt PPPPSSSSTTTTWWWWrrrriiiitttteeeeIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((SSSSTTTTSSSSttttrrrreeeeaaaammmm ****sssstttt,,,, PPPPSSSSTTTTIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr ****hhhhdddd,,,,
  19.                             iiiinnnntttt llllaaaasssstttt))));;;;
  20.  
  21. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  22.      These functions are similar to the generic _l_i_b_s_t_i_f_f functions
  23.      _S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r and _S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r. They differ only in the amount
  24.      of header information. The printing specific image header functions
  25.      _P_S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r and _P_S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r use an image header structure
  26.      that is a superset of the _S_T_I_m_a_g_e_H_e_a_d_e_r structure. The printing specific
  27.      header contains additional printing specific information such as image
  28.      resolution.
  29.  
  30.      Refer to the manual page for _S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r(_3) for information
  31.      regarding the role of the image header in a STIFF stream.
  32.  
  33.      _P_S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r reads the image header information from the stream
  34.      specified by _s_t and places the information in the image header structure
  35.      specified by _h_d. _s_t must point to a STIFF stream open for reading.
  36.      Following a successful call to _P_S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r, the function _S_T_R_e_a_d
  37.      can be called to read the actual image data. The amount of image data
  38.      available can be found in the _P_S_T_I_m_a_g_e_H_e_a_d_e_r structure.  In addition,
  39.      following a successful call to _P_S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r the TIFF tag list read
  40.      from the STIFF stream can be queried using the _S_T_G_e_t_T_a_g function. Note
  41.      that _P_S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r can be used to read a generic STIFF image header.
  42.      If the additional information required for the printing specific header
  43.      is not found in the stream, default values are placed in the
  44.      _P_S_T_I_m_a_g_e_H_e_a_d_e_r fields for which information was not found in the STIFF
  45.      stream as follows:
  46.  
  47.                     PPPPSSSSTTTTIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr ffffiiiieeeelllldddd   DDDDeeeeffffaaaauuuulllltttt VVVVaaaalllluuuueeee
  48.                     ___________________________________________
  49.                     resUnit                PST_RES_UNIT_INCH
  50.                     xRes                   0
  51.                     yRes                   0
  52.                     thresholding           PST_THRESHOLD_NONE
  53.                     compression            PST_COMPRESSION_NONE
  54.                     dataTime               "" (empty string)
  55.                     hostComputer           "" (empty string)
  56.                     software               "" (empty string)
  57.                     docName                "" (empty string)
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PPPPSSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((3333))))            IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo             PPPPSSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((3333))))
  71.  
  72.  
  73.  
  74.                     pageNumbers            0, 0
  75.                     targetPrinter          "" (empty string)
  76.                     driverOptions          "" (empty string)
  77.  
  78.      After all the last image has been read from a STIFF stream, the next call
  79.      to _P_S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r will return -1, and _S_T_e_r_r_n_o will be set to SSSSTTTTEEEEEEEEOOOOFFFF
  80.      (see below).
  81.  
  82.      _P_S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r writes a printing specific image header to the STIFF
  83.      stream specified by _s_t. Before a call to _P_S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r any caller
  84.      specific TIFF tags should be added to the output tag list using the
  85.      _S_T_A_d_d_T_a_g function. Following a successful call to _P_S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r the
  86.      actual image data can be written to the stream using _S_T_W_r_i_t_e. The amount
  87.      of image data that must be written to the stream is specified in the
  88.      _P_S_T_I_m_a_g_e_H_e_a_d_e_r structure.
  89.  
  90.      Make sure that all fields of the PPPPSSSSTTTTIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr structure passed to
  91.      _P_S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r contain reasonable values; otherwise, garbage will be
  92.      written into the STIFF stream.
  93.  
  94.      Note that following a successful call to _P_S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r the output
  95.      TIFF tag list is cleared. A STIFF stream written using
  96.      _P_S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r can be read using the generic _l_i_b_s_t_i_f_f image header
  97.      reading function _S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r. The additional information in the
  98.      stream will be placed on the tag list and may be queried using the
  99.      _S_T_G_e_t_T_a_g function.
  100.  
  101.      The _P_S_T_I_m_a_g_e_H_e_a_d_e_r structure is defined as follows.
  102.  
  103.           typedef struct pst_imghdr {
  104.               unsigned long width, height;    /* Dimensions in dots */
  105.               unsigned short bitsPerSample;   /* Bits per channel */
  106.               unsigned short samplesPerPixel; /* # of color channels */
  107.               unsigned long imgbytes;         /* Bytes of image data */
  108.               STType type;                    /* Image data type */
  109.               STPlane plane;                  /* Planar configuration */
  110.               PSTResUnit resUnit;             /* Resolution units */
  111.               unsigned long xRes, yRes;       /* Resolution, dots/resUnit */
  112.               PSTThreshold thresholding;      /* Dither mechanism */
  113.               PSTCompression compression;     /* Compression method */
  114.               char *dateTime;                 /* Image time stamp */
  115.               char *hostComputer;             /* Computer used */
  116.               char *software;                 /* Software used */
  117.               char *docName;                  /* Document name */
  118.               char *targetPrinter;            /* Destination printer */
  119.               unsigned short pageNumbers[2];  /* Page numbers */
  120.                                               /* [0] = current page # */
  121.                                               /* [1] = total pages */
  122.                                               /*       (0 = unknown) */
  123.               char *driverOptions;            /* Driver options */
  124.           } PSTImageHeader;
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PPPPSSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((3333))))            IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo             PPPPSSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((3333))))
  137.  
  138.  
  139.  
  140. TTTTIIIIFFFFFFFF TTTTAAAAGGGGSSSS UUUUSSSSEEEEDDDD
  141.      The _P_S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r function will write the TIFF tags listed below
  142.      into the STIFF stream. Any Caller specific tags added using _S_T_A_d_d_T_a_g(3)
  143.      are written in addition to the tags listed. The tags are expressed in
  144.      terms of their names in the header file _s_t_i_f_f._h. An '*' following a tag
  145.      name indicates that this tag is not used in the generic STIFF stream.
  146.  
  147.      STBitsPerSample
  148.      STCompression*
  149.      STDateTime*
  150.      STDocumentName*
  151.      STHostComputer*
  152.      STImageLength
  153.      STImageWidth
  154.      STNewSubfileType*
  155.      STPageNumber*
  156.      STPhotometricInterpretation
  157.      STPlanarConfiguration
  158.      STResolutionUnit*
  159.      STSamplesPerPixel
  160.      STSGIPrinting*
  161.      STSoftware*
  162.      STStripByteCounts
  163.      STStripOffsets
  164.      STTargetPrinter*
  165.      STThresholding*
  166.      STXResolution*
  167.      STYResolution*
  168.  
  169. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  170.      Both _P_S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r and _P_S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r return 0 if execution was
  171.      successful. -1 is returned and _S_T_e_r_r_n_o is set if an execution error has
  172.      occurred.
  173.  
  174. EEEEXXXXEEEECCCCUUUUTTTTIIIIOOOONNNN EEEERRRRRRRROOOORRRR CCCCOOOODDDDEEEESSSS
  175.      _P_S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r will fail under the following circumstances.
  176.  
  177.      STEBADTAG                Invalid TIFF tag.
  178.  
  179.      STENOMEM                 Out of memory.
  180.  
  181.      STEREADFROMWRITE         Attempt to read from a write stream.
  182.  
  183.      STESYSCALL               System call failed.
  184.  
  185.      STENEEDSEEK              Operation requires seeking on a stream.
  186.  
  187.      STEEOF                   End of stream.
  188.  
  189.      _P_S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r will fail under the following circumstances.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. PPPPSSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((3333))))            IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo             PPPPSSSSTTTTRRRReeeeaaaaddddIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr((((3333))))
  203.  
  204.  
  205.  
  206.      STEBADTAG                Invalid TIFF tag.
  207.  
  208.      STENOMEM                 Out of memory.
  209.  
  210.      STEWRITETOREAD           Attempt to write to a read only stream.
  211.  
  212.      STESYSCALL               System call failed.
  213.  
  214.      STENEEDSEEK              Operation requires seeking on a stream.
  215.  
  216. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  217.      libstiff(3), STReadImageHeader(3), STAddTag(3)
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.